Skip to content

Give each source its own command, and keep diff hidden as it was - #75

Merged
Mpdreamz merged 1 commit into
mainfrom
commands
Nov 14, 2026
Merged

Mpdreamz merged 1 commit into
mainfrom
commands

Conversation

@Mpdreamz

Copy link
Copy Markdown
Contributor

assembly-differ now has a command per source: release, files, nuget and github. Each takes typed arguments and the shared options -t, -f, -o and --fail-on. diff and its provider specs still work unchanged, hidden from help.

Prompt summary: The tool is being dusted off. Two strings split on |, with every flag shared by every source, are hard to read and hard to get right. argh can do better by making each source a proper subcommand. Existing callers must not break, so the current diff stays and is hidden.

Why

Every comparison was diff "<provider>|<arg>|<arg>" "<provider>|<arg>". The help could not say which parts a provider takes, a typo surfaced as an exception, and a CI build had to repeat the package id and version it had just packed. --help listed one command whose usage was spread over a single parameter description.

What

A command per source

release <path> compares a build with the release before it on nuget.org. Given a .nupkg, it reads the package id and version from it, so assembly-differ release build/output/MyLib.1.3.0.nupkg is the whole command. files <old> <new> takes a .dll, a directory or a .nupkg on each side. nuget <id> <old> <new> compares two published versions. github builds an older commit with the command you give. Each has its own --help, with examples.

Packages as input

A new provider reads a .nupkg and unpacks the assemblies of one target framework. --framework picks it. By default, files and release take the newest framework both sides ship, preferring .NET over .NET Standard over .NET Framework, and fail with a message when they share none.

Shared options

-t, -f, -o and --fail-on come from one [AsParameters] class, and argh validates --format and --fail-on against their allowed values. The default format of the commands is markdown; diff keeps xml. --fail-on stays a string until an argh release carries the enum default fix from nullean/argh#151.

diff unchanged

The comparison moved into DiffRunner, which diff and the commands share. diff is [Hidden], still the default command, and every characterization snapshot is unchanged. The root help describes the tool and lists the new commands.

Docs

Both READMEs lead with the commands and keep a short section on provider specs. They also correct two claims: a provider spec without diff works, and Proc 0.13.0 marks NoWrapInThread obsolete; it does not add it.

Verify

mise run test
# CommandsTests: help for every command, files on dlls, directories and generated .nupkgs,
# release and nuget against nuget.org
./build.sh smokeaot   # now also runs the nuget command with the native-AOT binary

Out of scope: release still fails when no earlier release exists. The next pull request resolves the baseline, including a first release. action.yml still calls diff; the action gets its own pull request.

🤖 Generated with Claude Code

Both sides were provider specs, strings such as previous-nuget|MyLib|1.3.0
split on pipes, with flags shared by every source. release, files, nuget
and github now take typed arguments and share -t, -f, -o and --fail-on;
release reads the package id and version from a .nupkg, and files and
release compare .nupkg files on the newest framework both sides ship. diff
runs the same comparison, hidden from help, so existing builds keep
working.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@Mpdreamz Mpdreamz added the feature A new capability (minor bump) label Nov 14, 2026
@Mpdreamz
Mpdreamz merged commit 910bd7f into main Nov 14, 2026
6 of 7 checks passed
@Mpdreamz
Mpdreamz deleted the commands branch November 14, 2026 07:58
Mpdreamz added a commit that referenced this pull request Nov 14, 2026
Run without a command in a repository, assembly-differ now compares
every library project's Release build with the latest release of its
package. It skips test projects and projects that are not packable, and
it does not build.

**Prompt summary:** Running assembly-differ without arguments, in a
directory with a solution or project file, should report the changes by
itself. That makes it easy for people and coding agents alike. It skips
test projects and `IsPackable=false` projects, each of which a flag
includes, and a project flag picks projects. Building is left to the
user, with a warning when there is no build output. The `--build`
orchestration of the `github` command is the tool doing too much, so it
goes.

## Why
To see what a change does to a library's API, a person or an agent had
to know the package id, the last version, the target framework and where
the build output lives, then spell all of it out. An agent checking a
change usually decompiled the assemblies itself instead.

## What

#### `projects`, the default command
The command reads the one `.slnx` or `.sln` in the directory through
`dotnet sln list`, or else its project files. It asks MSBuild for
`IsPackable`, `IsTestProject`, `PackageId`, `AssemblyName` and the
target frameworks. For the newest framework, it finds the Release
`TargetPath` and compares it with the latest stable release of the
package on the NuGet.config feeds. Every project goes into one report.
Each skipped project gets a line saying why and which flag includes it.
A package with no release, or one that ships no matching assembly, such
as a tool package, is reported and skipped.

#### No building
The tool does not build. A project without Release output is skipped
with a warning that says to run `dotnet build -c Release`. `--project`
picks project files explicitly, whatever kind they are. Two provider
specs passed straight to the root, as before commands existed, are
routed to `diff`, so those callers still work.

#### `github` command dropped, `github|` spec deprecated
The `github` command cloned another commit and ran a build command the
user had to spell out; it merged in
[#75](#75) and was never
released. The `github|...` spec in the hidden `diff` still works and now
warns on stderr. The README shows the replacement: `git worktree add`,
`dotnet build`, then `assembly-differ files`.

#### A crash fixed
A package with no assemblies under `lib/`, such as one that only ships
an analyzer, crashed the NuGet provider with "Sequence contains no
elements". It now reports that and compares nothing.

## Verify
```bash
mise run test
# ProjectsTests build a small solution for real: a library with a release on a local feed, a test project and an unpackable one
cd ~/Projects/argh && dotnet build -c Release && dotnet run --project <assembly-differ checkout>/src/assembly-differ -f net11.0 -c Release
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature A new capability (minor bump)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant